<?php

namespace Kunfeng\Dify\Client;

use Kunfeng\Dify\Callback\CompletionStreamCallback;
use Kunfeng\Dify\Exception\DifyApiException;
use Kunfeng\Dify\Model\Completion\CompletionRequest;
use Kunfeng\Dify\Model\Completion\CompletionResponse;
use Kunfeng\Dify\Model\Common\SimpleResponse;

/**
 * Dify 文本生成型应用客户端接口
 */
interface DifyCompletionClientInterface extends DifyBaseClientInterface
{
    /**
     * 发送文本生成请求（阻塞模式）
     */
    public function sendCompletionMessage(CompletionRequest $request): CompletionResponse;

    /**
     * 发送文本生成请求（流式模式）
     */
    public function sendCompletionMessageStream(CompletionRequest $request, CompletionStreamCallback $callback): void;

    /**
     * 停止文本生成
     */
    public function stopCompletion(string $taskId, string $user): SimpleResponse;

    /**
     * 文字转语音
     */
    public function textToAudio(?string $messageId, ?string $text, string $user): string;
}
